<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
  <meta content="text/html; charset=ISO-8859-1"
 http-equiv="content-type">
  <title>Dead Souls debugging</title>
  <link rel="icon" href="./favicon.ico" type="image/x-icon">
  <link rel="shortcut icon" href="./favicon.ico" type="image/x-icon">
</head>
<body>
<big style="font-family: courier new,courier,monospace;"><big><big><span
 style="font-weight: bold;">Debugging
in Dead Souls</span></big></big></big><br
 style="font-family: courier new,courier,monospace;">
<br style="font-family: courier new,courier,monospace;">
<span style="font-family: courier new,courier,monospace;">So you've
made some cool stuff but darn it, it doesn't work. There are
various</span><br style="font-family: courier new,courier,monospace;">
<span style="font-family: courier new,courier,monospace;">tools
available in the Dead Souls lib to hunt down the source of the
problem:</span><br style="font-family: courier new,courier,monospace;">
<br style="font-family: courier new,courier,monospace;">
<a style="font-family: courier new,courier,monospace;" href="#1">1 elog</a><br
 style="font-family: courier new,courier,monospace;">
<a style="font-family: courier new,courier,monospace;" href="#2">2
dbxframe and dbxwhere</a><br
 style="font-family: courier new,courier,monospace;">
<a style="font-family: courier new,courier,monospace;" href="#3">3
tell_player() and debug()</a><br
 style="font-family: courier new,courier,monospace;">
<a style="font-family: courier new,courier,monospace;" href="#4">4 tail</a><br
 style="font-family: courier new,courier,monospace;">
<a style="font-family: courier new,courier,monospace;" href="#5">5 bk
and restore</a><br style="font-family: courier new,courier,monospace;">
<br>
<br style="font-family: courier new,courier,monospace;">
<big style="font-family: courier new,courier,monospace;"><big
 style="font-weight: bold; text-decoration: underline;"><big><a name="1"></a>elog</big></big></big><br
 style="font-family: courier new,courier,monospace;">
<pre style="font-family: courier new,courier,monospace;"><big>If the file is somewhere in your home directory, just type: <span
 style="font-weight: bold;">elog</span> <br><br>This will provide you a listing of the last few lines of your personal<br>error log. Warning lines tell you about code that works but should<br>be fixed in some way. Lines that don't contain the word "Warning" are<br>error lines: they indicate something about your code that prevents<br>it from working. For example:<br><br></big></pre>
<hr
 style="width: 100%; height: 2px; font-family: courier new,courier,monospace;"><span
 style="font-family: courier new,courier,monospace;">&gt; </span><span
 style="font-weight: bold; font-family: courier new,courier,monospace;">update
sample_room</span><br
 style="font-family: courier new,courier,monospace;">
<pre style="font-family: courier new,courier,monospace;"><big><span
 style="font-style: italic;"></span><span style="font-style: italic;">---<br>*Error in loading object '/realms/cratylus/area/room/sample_room'<br>Object: /secure/cmds/creators/update at line 148<br><br>'&lt;function&gt;' at /secure/save/creators/c/cratylus (&lt;function&gt;) at /:0<br>'cmdAll' at /secure/save/creators/c/cratylus (/lib/command.c) at line 84<br>'cmd' at /secure/cmds/creators/update at line 109<br>'eventUpdate' at /secure/cmds/creators/update at line 148<br>'CATCH' at /secure/cmds/creators/update at line 148<br>Trace written to /log/catch<br>/realms/cratylus/area/room/sample_room: Error in update<br>*Error in loading object '/realms/cratylus/area/room/sample_room'<br></span></big></pre>
<hr
 style="width: 100%; height: 2px; font-family: courier new,courier,monospace;">
<pre style="font-family: courier new,courier,monospace;"><big><span
 style="font-style: italic;"><br></span><br>	This output lets you know something is wrong, but<br>isn't very specific as to exactly what. If you look at your error<br>log, you probably will see something more detailed and helpful:<br><br><br></big></pre>
<hr
 style="width: 100%; height: 2px; font-family: courier new,courier,monospace;"><span
 style="font-family: courier new,courier,monospace;">&gt; </span><span
 style="font-weight: bold; font-family: courier new,courier,monospace;">elog</span><br
 style="font-family: courier new,courier,monospace;">
<pre style="font-family: courier new,courier,monospace;"><big><span
 style="font-style: italic;">/log/errors/cratylus:</span><br
 style="font-style: italic;"><br style="font-style: italic;"><span
 style="font-style: italic;"></span><span style="font-style: italic;">/realms/cratylus/area/room/sample_room.c line 10: Undefined variable 'Sample'<br>/realms/cratylus/area/room/sample_room.c line 10: parse error<br></span></big></pre>
<hr
 style="width: 100%; height: 2px; font-family: courier new,courier,monospace;">
<pre style="font-family: courier new,courier,monospace;"><big><span
 style="font-style: italic;"><br></span><br>	Now you can see that the error is my syntax on<br>line 10. I would then use ed to examine the code, and specifically lines 9<br>through 11. It turns out that I forgot to put quotes around the room name, <br>so the parser tried to use it as a variable, which, of course, it couldn't.<br><br>	If the file in question is in /secure, you'd type <span
 style="font-weight: bold;">elog secure</span> , or if<br>it's in /cmds, <span
 style="font-weight: bold;">elog cmds</span> , and so on.<br><span
 style="font-weight: bold;"><br>	</span></big><br><big><big
 style="font-weight: bold; text-decoration: underline;"><big><a name="2"></a></big></big></big><big><big
 style="font-weight: bold; text-decoration: underline;"><big>dbxwhere</big></big></big><big><big
 style="font-weight: bold; text-decoration: underline;"><big> &amp; dbxframe</big></big><span
 style="font-weight: bold;"><br></span></big><big><span
 style="font-weight: bold;"></span></big><big><span
 style="font-weight: bold;"><br>	</span>Two<span
 style="font-weight: bold;"> </span>helpful debugging commands are dbxframe and dbxwhere. Let's<br>take a look at my broken sample_room.c file. We'll start with dbxwhere,<br>which lists for us the chain of events that led to the error. The<br>individual steps are called frames.<br><br>&gt; <span
 style="font-weight: bold;">dbxwhere</span><br>*Error in loading object '/realms/cratylus/area/room/sample_room'<br>Object: /secure/cmds/creators/update at line 148<br><br>#0: '&lt;function&gt;' at /secure/save/creators/c/cratylus (&lt;function&gt;) at /:0<br>#1: 'cmdAll' at /secure/save/creators/c/cratylus (/lib/command.c) at line 84<br>#2: 'cmd' at /secure/cmds/creators/update at line 109<br>#3: 'eventUpdate' at /secure/cmds/creators/update at line 148<br>#4: 'CATCH' at /secure/cmds/creators/update at line 148<br></big></pre>
<br style="font-family: courier new,courier,monospace;">
<span style="font-family: courier new,courier,monospace;">The output is
similar to the update error we saw above, but in
enumerating the steps, </span><span
 style="font-weight: bold; font-family: courier new,courier,monospace;">dbxwhere</span><br
 style="font-family: courier new,courier,monospace;">
<span style="font-family: courier new,courier,monospace;">lets us use </span><span
 style="font-weight: bold; font-family: courier new,courier,monospace;">dbxframe</span><span
 style="font-family: courier new,courier,monospace;"> to get
tighter detail on a given error frame:</span><br
 style="font-family: courier new,courier,monospace;">
<br style="font-family: courier new,courier,monospace;">
<span style="font-family: courier new,courier,monospace;">&gt; </span><span
 style="font-weight: bold; font-family: courier new,courier,monospace;">dbxframe
4</span><br style="font-family: courier new,courier,monospace;">
<span style="font-family: courier new,courier,monospace;">------</span><br
 style="font-family: courier new,courier,monospace;">
<span style="font-family: courier new,courier,monospace;">&nbsp;&nbsp;&nbsp;
/secure/cmds/creators/update.c:148 - CATCH(0)</span><br
 style="font-family: courier new,courier,monospace;">
<span style="font-family: courier new,courier,monospace;">&nbsp;&nbsp;&nbsp;
----------------------------------------------------------------</span><br
 style="font-family: courier new,courier,monospace;">
<span style="font-family: courier new,courier,monospace;">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
if( args == base_name(this_object()) ) {</span><br
 style="font-family: courier new,courier,monospace;">
<span style="font-family: courier new,courier,monospace;">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
this_player()-&gt;eventPrint("Cannot reload update after destruct.\n"</span><br
 style="font-family: courier new,courier,monospace;">
<span style="font-family: courier new,courier,monospace;">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
"It will be reloaded at next reference.");</span><br
 style="font-family: courier new,courier,monospace;">
<span style="font-family: courier new,courier,monospace;">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
return 0;</span><br style="font-family: courier new,courier,monospace;">
<span style="font-family: courier new,courier,monospace;">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
}</span><br style="font-family: courier new,courier,monospace;">
<span style="font-family: courier new,courier,monospace;">&nbsp;&nbsp;&nbsp;
=&gt;&nbsp;
tmp = catch(call_other(args, "???"));</span><br
 style="font-family: courier new,courier,monospace;">
<span style="font-family: courier new,courier,monospace;">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
if( !tmp ) {</span><br
 style="font-family: courier new,courier,monospace;">
<span style="font-family: courier new,courier,monospace;">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
if(identify(flags ^ U_AUTOMATED) ==</span><br
 style="font-family: courier new,courier,monospace;">
<span style="font-family: courier new,courier,monospace;">&nbsp;&nbsp;&nbsp;
"8")this_player()-&gt;eventPrint(args + ": Ok");</span><br
 style="font-family: courier new,courier,monospace;">
<span style="font-family: courier new,courier,monospace;">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
return 1;</span><br style="font-family: courier new,courier,monospace;">
<span style="font-family: courier new,courier,monospace;">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
} else this_player()-&gt;eventPrint(args + ": Error in update\n" + tmp);</span><br
 style="font-family: courier new,courier,monospace;">
<span style="font-family: courier new,courier,monospace;">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
return 0;</span><br style="font-family: courier new,courier,monospace;">
<br style="font-family: courier new,courier,monospace;">
<br style="font-family: courier new,courier,monospace;">
<span style="font-family: courier new,courier,monospace;">&nbsp;&nbsp;&nbsp;
We're now looking at the error context for error
frame 4. The output of the command shows</span><br
 style="font-family: courier new,courier,monospace;">
<span style="font-family: courier new,courier,monospace;">us part of
the file that was performing the evaluation when the error
occurred, and even</span><br
 style="font-family: courier new,courier,monospace;">
<span style="font-family: courier new,courier,monospace;">points out
the offending line using a text arrow: =&gt;</span><br
 style="font-family: courier new,courier,monospace;">
<br style="font-family: courier new,courier,monospace;">
<span style="font-family: courier new,courier,monospace;">&nbsp;&nbsp;&nbsp;
In this particular case, the information is not that
helpful. We are being told that</span><br
 style="font-family: courier new,courier,monospace;">
<span style="font-family: courier new,courier,monospace;">the error
occurred while we were using the update command, and it
failed at the line</span><br
 style="font-family: courier new,courier,monospace;">
<span style="font-family: courier new,courier,monospace;">where update
does its thing. Duh, we knew that. The </span><span
 style="font-weight: bold; font-family: courier new,courier,monospace;">elog</span><span
 style="font-family: courier new,courier,monospace;"> command was much
more helpful.</span><br
 style="font-family: courier new,courier,monospace;">
<br style="font-family: courier new,courier,monospace;">
<span style="font-family: courier new,courier,monospace;">&nbsp;&nbsp;&nbsp;
Where this kind of tracing comes in handy is when
you encounter a runtime error</span><br
 style="font-family: courier new,courier,monospace;">
<span style="font-family: courier new,courier,monospace;">when you're
not updating a file. For example, if I tried to enter that
room, rather than</span><br
 style="font-family: courier new,courier,monospace;">
<span style="font-family: courier new,courier,monospace;">update it,
I'd get a big pukey error message and not know why. If you
run into an</span><br
 style="font-family: courier new,courier,monospace;">
<span style="font-family: courier new,courier,monospace;">unexpected
error, </span><span
 style="font-weight: bold; font-family: courier new,courier,monospace;">dbxwhere</span><span
 style="font-family: courier new,courier,monospace;">
will help you pinpoint it if </span><span
 style="font-weight: bold; font-family: courier new,courier,monospace;">elog</span><span
 style="font-family: courier new,courier,monospace;">
doesn't provide useful information,</span><br
 style="font-family: courier new,courier,monospace;">
<span style="font-family: courier new,courier,monospace;">and </span><span
 style="font-weight: bold; font-family: courier new,courier,monospace;">dbxframe</span><span
 style="font-family: courier new,courier,monospace;"> will help detail
the source of the problem.<br>
<br>
<big><big><br>
<big><span style="font-weight: bold; text-decoration: underline;"></span></big></big></big></span><big
 style="font-family: courier new,courier,monospace;"><big
 style="font-weight: bold; text-decoration: underline;"><big><a name="3"></a></big></big></big><span
 style="font-family: courier new,courier,monospace;"><big><big><big><span
 style="font-weight: bold; text-decoration: underline;">tell_player(),
debug()</span></big></big></big><br>
<br>
&nbsp;&nbsp;&nbsp; Sometimes it's hard to fix code if you don't know
what it's doing. In<br>
the above example, you might want to know what the variable "args" is,
if<br>
your code is behaving unexpectedly. You could find out by adding a line
like:<br>
<br>
<span style="color: rgb(0, 0, 153);">tell_player("cratylus", "args is:
"+identify(args));<br>
<br>
<span style="color: rgb(0, 0, 0);">or:</span><br>
<br>
</span><span style="color: rgb(0, 0, 153);">tell_player("cratylus",
"%^BLUE%^args
is: "+identify(args)+"%^RESET%^");</span></span><br
 style="color: rgb(0, 0, 153); font-family: courier new,courier,monospace;">
<span style="font-family: courier new,courier,monospace;"><span
 style="color: rgb(0, 0, 153);"></span><br>
&nbsp;&nbsp;&nbsp; You could also use:<br>
<br>
<span style="color: rgb(0, 0, 153);">debug("args is: ", args);<br>
<br>
<span style="color: rgb(0, 0, 0);">or:</span><br>
<br>
</span><span style="color: rgb(0, 0, 153);">debug("args is: ", args,
"blue");</span></span><br
 style="font-family: courier new,courier,monospace;">
<span style="font-family: courier new,courier,monospace;"><span
 style="color: rgb(0, 0, 153);"></span><br>
&nbsp;&nbsp;&nbsp; ...which has the advantage of being shorter to type
and you'll get<br>
the message more promptly. To be able to receive debug messages,<br>
you need to enable your debugging mode by typing:<br>
<br style="font-weight: bold;">
<span style="font-weight: bold;">debug on</span><br>
<br>
&nbsp;&nbsp;&nbsp; debug() is available in 2.0r20 and above.<br>
</span><br style="font-family: courier new,courier,monospace;">
<pre
 style="font-weight: bold; text-decoration: underline; font-family: courier new,courier,monospace;"><big><big
 style="font-weight: bold; text-decoration: underline;"><big><a name="4"></a></big></big></big><big><big><big>tail</big></big></big></pre>
<br style="font-family: courier new,courier,monospace;">
<span style="font-family: courier new,courier,monospace;">&nbsp;&nbsp;&nbsp;
This is a version of the unix tail command. It
displays the last few lines of a file. </span><br
 style="font-family: courier new,courier,monospace;">
<span style="font-family: courier new,courier,monospace;">This command
is important for examining crucial log files:</span><br
 style="font-family: courier new,courier,monospace;">
<br style="font-family: courier new,courier,monospace;">
<span
 style="font-weight: bold; font-family: courier new,courier,monospace;">tail
/log/catch</span><big
 style="font-family: courier new,courier,monospace;"><br>
<small style="font-weight: bold;">tail /log/runtime<br>
</small></big><big style="font-family: courier new,courier,monospace;"><small
 style="font-weight: bold;">tail
/log/player_errors<br>
<br>
<br>
</small></big><big style="font-family: courier new,courier,monospace;"><big
 style="font-weight: bold; text-decoration: underline;"><big><a name="5"></a></big></big></big><big
 style="text-decoration: underline; font-family: courier new,courier,monospace;"><big><big><span
 style="font-weight: bold;">bk
&amp; restore</span><br>
<br>
</big></big></big><span
 style="font-family: courier new,courier,monospace;">These commands
aren't so much for debugging as they
are for safe coding. Before you</span><br
 style="font-family: courier new,courier,monospace;">
<span style="font-family: courier new,courier,monospace;">edit a file,
it is a very good idea to back it up first. The </span><span
 style="font-weight: bold; font-family: courier new,courier,monospace;">bk</span><span
 style="font-family: courier new,courier,monospace;"> command lets you</span><br
 style="font-family: courier new,courier,monospace;">
<span style="font-family: courier new,courier,monospace;">quickly and
conveniently back up a file before you edit it. When I
typed:</span><br style="font-family: courier new,courier,monospace;">
<br style="font-family: courier new,courier,monospace;">
<span
 style="font-weight: bold; font-family: courier new,courier,monospace;">bk
sample_room</span><br
 style="font-family: courier new,courier,monospace;">
<br style="font-family: courier new,courier,monospace;">
<span style="font-family: courier new,courier,monospace;">A file with a
unique identifying number was created in my bak/
directory. If I</span><br
 style="font-family: courier new,courier,monospace;">
<span style="font-family: courier new,courier,monospace;">were to type
it again, then sample_room.c would get copied again to
bak/, with</span><br style="font-family: courier new,courier,monospace;">
<span style="font-family: courier new,courier,monospace;">a new unique
number added to the name.</span><br
 style="font-family: courier new,courier,monospace;">
<br style="font-family: courier new,courier,monospace;">
<span style="font-family: courier new,courier,monospace;">&nbsp;&nbsp;&nbsp;
The number is basically the number of seconds
elapsed since January 1, 1970.</span><br
 style="font-family: courier new,courier,monospace;">
<span style="font-family: courier new,courier,monospace;">Adding this
number, we can keep track of which backed up version of a
file</span><br style="font-family: courier new,courier,monospace;">
<span style="font-family: courier new,courier,monospace;">is most
recent by looking at the name.</span><br
 style="font-family: courier new,courier,monospace;">
<br style="font-family: courier new,courier,monospace;">
<span style="font-family: courier new,courier,monospace;">&nbsp;&nbsp;&nbsp;
Suppose I edited a file called sample_npc.c. I use
bk to back it up, make some changes,</span><br
 style="font-family: courier new,courier,monospace;">
<span style="font-family: courier new,courier,monospace;">then use bk
again, make some more changes, but now it won't update. I
don't</span><br style="font-family: courier new,courier,monospace;">
<span style="font-family: courier new,courier,monospace;">feel like
debugging, I just need this file working again, so I want to
restore from</span><br
 style="font-family: courier new,courier,monospace;">
<span style="font-family: courier new,courier,monospace;">backup. The
sequence of commands would look something like this:</span><br
 style="font-family: courier new,courier,monospace;">
<br style="font-family: courier new,courier,monospace;">
<span
 style="font-weight: bold; font-family: courier new,courier,monospace;">ed
sample_npc.c</span><br
 style="font-weight: bold; font-family: courier new,courier,monospace;">
<span
 style="font-weight: bold; font-family: courier new,courier,monospace;">bk
sample_npc</span><br
 style="font-weight: bold; font-family: courier new,courier,monospace;">
<span
 style="font-weight: bold; font-family: courier new,courier,monospace;">ed
sample_npc.c</span><br
 style="font-weight: bold; font-family: courier new,courier,monospace;">
<span
 style="font-weight: bold; font-family: courier new,courier,monospace;">update
sample_npc.c</span><br
 style="font-family: courier new,courier,monospace;">
<span
 style="color: rgb(204, 0, 0); font-family: courier new,courier,monospace;">&lt;error
occurs here&gt;</span><br
 style="font-family: courier new,courier,monospace;">
<span
 style="font-weight: bold; font-family: courier new,courier,monospace;">restore
sample_npc</span><br style="font-family: courier new,courier,monospace;">
<br style="font-family: courier new,courier,monospace;">
<span style="font-family: courier new,courier,monospace;">&nbsp;&nbsp;&nbsp;
The reason identifying numbers are used is that you
can also choose to</span><br
 style="font-family: courier new,courier,monospace;">
<span style="font-family: courier new,courier,monospace;">restore the
second-to-last backup version of a file, and other previous</span><br
 style="font-family: courier new,courier,monospace;">
<span style="font-family: courier new,courier,monospace;">versions.</span><br
 style="font-family: courier new,courier,monospace;">
<span style="font-family: courier new,courier,monospace;">&nbsp;&nbsp;&nbsp;
The very last backup version is effectively version
0, so it's not</span><br
 style="font-family: courier new,courier,monospace;">
<span style="font-family: courier new,courier,monospace;">necessary to
specify a number. If I wanted to restore the version I
backed</span><br style="font-family: courier new,courier,monospace;">
<span style="font-family: courier new,courier,monospace;">up before
that one, I would type something like this:</span><br
 style="font-family: courier new,courier,monospace;">
<br style="font-family: courier new,courier,monospace;">
<span
 style="font-weight: bold; font-family: courier new,courier,monospace;">restore
sample_npc 1</span><br
 style="font-family: courier new,courier,monospace;">
<br style="font-family: courier new,courier,monospace;">
<span style="font-family: courier new,courier,monospace;">&nbsp;&nbsp;&nbsp;
And if I wanted the version before that one, I'd
specify 2 instead of 1, </span><br
 style="font-family: courier new,courier,monospace;">
<span style="font-family: courier new,courier,monospace;">and so on.</span><br
 style="font-family: courier new,courier,monospace;">
<br style="font-family: courier new,courier,monospace;">
<span style="font-family: courier new,courier,monospace;">&nbsp;&nbsp;&nbsp;
Please note that this is an intentionally simple
system. There are</span><br
 style="font-family: courier new,courier,monospace;">
<span style="font-family: courier new,courier,monospace;">no menus, no
version branches, or diff tracking. The reason for this is</span><br
 style="font-family: courier new,courier,monospace;">
<span style="font-family: courier new,courier,monospace;">that it is
not a </span><span
 style="font-style: italic; font-family: courier new,courier,monospace;">versioning</span><span
 style="font-family: courier new,courier,monospace;">
system. It is a </span><span
 style="font-style: italic; font-family: courier new,courier,monospace;">backup</span><span
 style="font-family: courier new,courier,monospace;">
system. It is a convenient</span><br
 style="font-family: courier new,courier,monospace;">
<span style="font-family: courier new,courier,monospace;">tool to back
out of screwups, not a development tool to test file
versions.</span><br style="font-family: courier new,courier,monospace;">
<big style="font-family: courier new,courier,monospace;"><small
 style="font-weight: bold;"><br>
<br>
</small></big><a style="font-family: courier new,courier,monospace;"
 href="index.html">Dead Souls Homepage</a><br
 style="font-family: courier new,courier,monospace;">
<big style="font-family: courier new,courier,monospace;"><small
 style="font-weight: bold;"><br>
<br>
</small></big>
</body>
</html>
